All dialogs contain dialog items - pictures, buttons, icons, pop-up menus etc. The items which the user interacts with (by typing or using the mouse) are called controls. It is important to choose the right type of control for your dialog, so that your module is consistent and easy to use.
Checkboxes
A checkbox is used to indicate a choice between two options, where one choice is clearly the opposite of the other. The text that accompanies a checkbox describes the option that is chosen when the box is 'checked'. An appropriate use of a checkbox might be
since it is obvious that visible is the opposite of invisible. An inappropriate use of a checkbox would be
since it is not obvious what the opposite of visible might be (hidden, for example). Likewise
is also inappropriate, since it is not immediately obvious what the opposite of male is. The last example is better served by radio buttons.
Radio buttons
Radio buttons are used to choose between two or more options that are mutually exclusive (that is, only one option may be chosen). Unlike other control types, radio controls are only useful in groups of two or more. The text to the right of a radio button describes the option that is chosen when that radio button is selected. In their simplest form, two radio buttons can be used to choose between two options. For example
Using two radio buttons may be preferable to using a checkbox (for example, when a long description for each option is required). More radio buttons can be used for more options. For example
Remember that radio buttons are used for exclusive options. So this set of options, for example
would be inappropriate if it were possible to be, say, invisible and flying at the same time. In this case, it would be better to use three checkboxes. When there are many items in a dialog, it is good practice to title a group of radio buttons, and to enclose them with a grey border if there are many other controls in the dialog. For example
Pop-up menus
A pop-up menu is used to choose between two or more options that are mutually exclusive. It is therefore the same as radio buttons, except that a pop-up menu takes up less space in the dialog. The text to the left of the pop-up menu is the title. The option chosen is displayed to the right of the title. When the menu is 'popped up', the option chosen has a tick beside it.
Edit text
An edit text item is used to enter text and numbers. The title is displayed to the left of the edit text field. An appropriate use of an edit text item could be
or
An inappropriate use for an edit text item is any use which could be achieved by another control.
You can use all of these types of controls in your module. In addition, you can also display variables as static text items, when you want the variable to be visible, but not editable.
Example: In the 'Heroes of Might & Magic - Heroes' module, the name of each hero is displayed at the top of the dialog, but cannot be edited.
Note that, with the exception of the Link fields used only with radio buttons, the 'ACEc' resource is independent of the dialog item used on screen. This means that you can display a variable as a edit text item initially, then change it to a different control simply by changing the dialog item. This is useful when building a module as it will allow you to see unexpected variable values which might be hidden by other control types. It is also a useful trick to aid in testing equations.
The C string, pascal string and character control types should only be displayed as edit text or static text items.
Where possible, the character control type should not be used. It is only necessary when a variable has a few widely varying values, which cannot be easily mapped to a pop-up menu or a set of radio buttons via an equation.
You can make group boxes by placing PICTs with id 11.
Control Linking
Controls can be 'linked' together so that the value of one control affects other controls. This is achieved by setting the Link fields of the 'ACEc' resource. Linking is currently implemented for two specific cases:
1. You can (and must) link radio buttons together. Link 1 is the first radio button in the group, link 2 is the last radio button in the group. Both radio buttons are specified as control numbers.
2. A pop-up menu can be linked to a list so that when the user selects an item from the pop-up menu, the list can change it's display. Link 1 is the (negative) list number of the list that the pop-up menu is linked to. This feature is detailed in "Development (Lists)".
Dialog Layout
Where possible, you should try to make the layout of the module dialog the same as the layout of the appropriate screen or dialog in the game. If this would be impractical, try to place the controls in a left-to-right and top-to-bottom order that mimics the game.
The numerical order of the dialog items (determined by their dialog item number) is significant. First, the order of the edit text items determines the order in which the selection moves through them when the user presses the tab key on non-appearance manager systems. An optimal edit text item layout is as follows:
Start with the top left edit text item, then go top to bottom, left to right. Example:
When the edit text item is part of a group (either implied or specifically designated by a grey border), then go top to bottom, left to right within the group before going to the next group. Go from group to group in a similar order. Example:
However, when the shape of the next group would require you to go left or up to the next group after that, then you should instead go right or down to the next group. Example:
On appearance manager savvy systems, the focus ring should follow the sequence described above. See the section "The Control Hierarchy" below for details on how to order the dialog items.
The control or static text item in the top left corner of the dialog should be offset from the both the top and left edge by a space of 10 pixels. The item in the lower right corner should also be offset from the bottom and right edge by 10 pixels.
Hint: Set the grid spacing to 10 pixels and turn on the Align to Grid option from the DITL menu in ResEdit. This will allow you to easily place the top left item. To correctly size the dialog so that the bottom right item is 10 pixels from the border, size the dialog so that the bottom right corner of the bottom right item is just touching the edge of the dialog as follows:
Now close the 'DITL' editor and open the 'DLOG' editor. Add 10 to the number in the Height and Width (or Bottom and Right) fields.
The alignment of items in a dialog may vary depending on the script system. In 'Roman' script systems (i.e. English), dialog items are aligned left to right, with the control proper (the checkbox or radio button) on the left hand side of the dialog item's rectangle, followed by the control text. When alignment is right to left, as in Hebrew or Arabic, the control manager automatically puts the control proper on the right hand side of the dialog item's rectangle. Therefore, when creating checkboxes, radio buttons and static text items that need to align, you should ensure that their display rectangles align on the right hand edge, as well as the left hand edge (i.e. the display rectangles are all the same size).
Example: Incorrectly sized display rectangles:
The same dialog box with right to left alignment - wrong!
A dialog box containing display rectangles of the same size
The same dialog with right to left alignment - correct!
When designing your dialog, remember to disable any extensions that alter the standard system font. When the system font has been changed to, say, Espi Sans, as used in the 'Aaron' and 'Kaleidoscope' extensions, the width of each character is smaller. Therefore a dialog designed in this font will not display correctly on a system using the standard Chicago font. Note that you cannot use the View As… command in ResEdit to view the dialog in Chicago while using one of the above mentioned extensions, as they will automatically map this selection back to Espi Sans!
If you are using MacOS 8.0 or greater, set the System Font in the Appearance control panel to Chicago while editing a dialog (the Charcoal font is slightly smaller than Chicago).
The Control Hierarchy
On systems that use the appearance manager, the order of DITL items has the additional effect of determining 'embedding'. Embedding simply allows dialog items to be placed 'inside' one another.
In ACE, embedding only affects group boxes. When you put a group box in your dialog, it must have a DITL id lower than all the items contained within it. If you do not do this, the group box will 'cover up' everything inside it.
Example: A dialog containing a group box
Incorrect: The group box id is greater than the items within it, so the group box covers the items.
Correct: The group box id is less than all the items within it, and the items display correctly.
Embedding also affects the focus order. Items that are not embedded in a group box will get focus priority, irrespective of their dialog item id. Focus order is still determined by dialog item id inside a group box. The dialog should be designed so that focus order is the same for appearance and non-appearance dialogs.
The best strategy for ordering dialog items in appearance manager dialogs is to number any items outside group boxes in the normal manner, then number all the group boxes in the order that you want the selection focus to move between them, then number the items inside each group box in the order you want the focus to move between them again.
Control Number and Dialog Item Id
There are two methods that can be used to associate 'ACEc' controls with dialog items. The first method is to assume that each control maps directly to the corresponding dialog item. The first control ('ACEc' resource id 128) maps to the dialog item with id 1, the second control ('ACEc' resource id 129) maps to dialog item id 2, and so forth.
The second method is to use a mapping table, which associates each control number with a dialog item id. This dialog mapping table is the 'ACEi' (ACE item) resource.
For the non-appearance manager dialog (DITL id 128), it is always possible to arrange the order of the dialog items so that each control directly corresponds to a dialog item (i.e. a mapping table is not necessary).
For the appearance manager dialog (DITL id 129), a mapping table is only necessary if the dialog contains one or more group boxes (group boxes must have a lower dialog item id that the items contained within them).
The tabbed windows (DITL id 130 and 131) must have an 'ACEi' resource.
Hint: If both tabbed windows have the same item mapping, you can create the 'ACEi' resource for one and then duplicate it, changing the duplicate's resource id (if necessary). This can occur when both root dialogs consist of just one dialog item, and both use the same pane dialogs.
See the section on the 'ACEi' resource in "Development (II)" for information on the fields of the 'ACEi' resource.
Equation Parser
Some games will use an 'internal representation' for variables that differs from what the game displays to the player. This can occur for a number of reasons:
• A programming convenience (it may be more efficient)
• Backwards compatibility with an older system or different processor type.
• A means of saving disc or memory space.
• A way or recording more information (representing two types of 'nothing' for example)
• The information displayed is not really what is recorded at all.
Clearly, these purposes can overlap.
Example: King's Bounty keeps a record of the number of troops in each army, and the type of creature in each army. If the character has no armies in an army 'slot', the army type is recorded as 255.
Example: In Marathon, the player initially possesses ammunition only for the pistol - the 'weapons manifest' does not display any other types of ammunition. If the player subsequently finds, and then uses up another type of ammunition, the weapons manifest displays '0' followed by the name of the ammunition. Marathon uses the value 255 to represent an ammunition type that has never been found, and the value 0 for one that has been found but has been fully depleted.
It is the internal representation that is often recorded in the game's save file.
It is desirable to display information in a way that the user is familiar with (i.e. the way the game displays that information), rather than the internal representation that may be used in the save file. Often this can be achieved by manipulating the variable with a known equation.
ACE! contains a small equation parser and interpreter†, which can be used to modify the value of variables before they are displayed, and before they are saved.
Syntax
The syntax for equations used is similar to the Basic programming language:
Mathematical operators:
+ plus
- minus
* multiplication
/ division
mod remainder after division
^ power
The mod operator requires it's argument to be preceded by a space or enclosed in brackets.
Logical operators:
and
or
xor exclusive-or
not
= equal
> greater than
< less than
<> not equal
Brackets () and parenthesis [] can be used to change precedence, and the usual rules of precedence apply. The (descending) order of precedence is therefore:
[ ] () not * / mod + - = <> < > <= >= and or
The following functions may be used:
sqr square root
sin sine
cos cosine
tan tangent
atan arc tan
log the natural logarithm (ln)
log10 the base-10 logarithm
exp exponential
abs absolute value
floor rounds a floating point number down to it's next lowest integer
Function arguments should be enclosed in brackets. All angles in trigonometric functions are measured in radians.
Two constants are defined:
pi i.e. π, defined as 3.141592653589793
e defined as 2.718281828459045
Lastly, two control constructs are included - an if…then statement and an while…wend, with the following syntax (EXPR is any valid mathematical expression):
if EXPR then EXPR : EXPR : ... endif
while (EXPR) EXPR : EXPR : ... wend
In general, spaces are optional, but must be used in control constructs if expressions are not enclosed in brackets.
Implementation
For each dialog control, you can nominate an equation that will be applied to the variable before it is displayed in the dialog (to convert from the internal representation to the user representation), and another equation that will be applied to the variable before it is saved (converting from the user representation back to the internal representation). This is achieved by the 'Equation to screen' and 'Equation to file' fields of the 'ACEc' resource. It is perfectly acceptable for one equation to be referenced by two or more controls.
The variable x is defined as the variable value from the file (in an 'Equation to screen') and as the variable value from the screen (in an 'Equation to file'). Therefore, all your equations will be mathematical operations on the variable x. The result of an equation is treated as an integer (any fractional component is truncated).
It is often useful to use an equation with a pop-up menu when one value in the pop-up menu is not part of a continuous sequence.
Example: In King's Bounty, the Armies variable has a value of 1 to 24 depending on the type of army, or 255 if there is no army in that slot. The armies used to be represented by a pop-up menu, with the last item in the pop-up being 'None'. The 'Equation to screen' was
if x=255 then x=26 endif
and the 'Equation to file' was
if x=26 then x=255 endif
Common errors with equations include
• Forgetting to write 'endif' at the end of a if…then construct
• Writing x= at the beginning of the equation (the x= is assumed for equations that are not constructs)
Testing
In general, the only way to test a module is to test the save file it edits - if the edited save file works under a variety of different situations, the module is working. However, be aware that if an edited save game crashes the game, or doesn't work as expected, this does not necessarily indicate that the module is at fault. The edited save game may be in a state that the game does not expect to exist. If you find such a condition, you should note it in the documentation for your module and in the Module Info screen.
The best way to test is to enter extreme values for controls. Initially, alter only one control at a time.
The following test is also helpful: Open the save game document in ACE! using your module. Choose Save A Copy As from the File menu and save under a new name. Now Quit ACE! and compare the original save game document with the new copy using a file comparison utility. If the two files are identical, then this is a good indication (but does not guarantee) that your module is working correctly.
You should also test that you module prints correctly. If you do not have access to a printer, use a printer driver that prints to a file, such as the Apple "LaserWriter 8" driver (version 8.4 or higher), or the "eDOC Creator" driver (included with the eDOC package). If you module does not print correctly, check that every 'ACEc' resource has a name.
_________
† The equation parser and interpreter was written by Ronald H. Nicholson, Jr. Please refer to the 'Legal' documentation for information on copyright and use.
